cli-truncate

What is cli-truncate?

The cli-truncate package is designed to truncate a string to a specific length without breaking the words, making it suitable for command-line interfaces where space is limited. It can handle strings with ANSI escape codes, ensuring that the visual formatting is preserved even when the string is truncated.

What are cli-truncate's main functionalities?

Truncate a string to a specific length

This feature allows you to truncate a string to a specified length, ensuring that the output fits within a certain space in the CLI. It's useful for displaying long strings in a limited space.

"const cliTruncate = require('cli-truncate');\nconsole.log(cliTruncate('unicorn', 4)); // => 'uni…'"

Preserve ANSI escape codes

This feature ensures that ANSI escape codes within the string are preserved when truncating. This is particularly useful for maintaining text styles (like colors) in the CLI output.

"const cliTruncate = require('cli-truncate');\nconsole.log(cliTruncate('\u001B[31municorn\u001B[39m', 4)); // => '\u001B[31muni…\u001B[39m'"

Specify the position of the truncation

This feature allows you to specify where the truncation should occur (start, middle, or end), giving you more control over how the truncated string looks.

"const cliTruncate = require('cli-truncate');\nconsole.log(cliTruncate('unicorn', 4, {position: 'middle'})); // => 'un…n'"

Other packages similar to cli-truncate

truncate-utf8-bytes

This package truncates strings based on byte length rather than character count, which is useful for ensuring that the string does not exceed byte limits. However, it does not specifically cater to CLI environments or preserve ANSI escape codes.

README

cli-truncate

Truncate a string to a specific width in the terminal

Gracefully handles ANSI escapes. Like a string styled with chalk. It also supports Unicode surrogate pairs and fullwidth characters.

Install

npm install cli-truncate

Usage

import cliTruncate from 'cli-truncate';

cliTruncate('unicorn', 4);
//=> 'uni…'

// Truncate at different positions
cliTruncate('unicorn', 4, {position: 'start'});
//=> '…orn'

cliTruncate('unicorn', 4, {position: 'middle'});
//=> 'un…n'

cliTruncate('unicorns rainbow dragons', 6, {position: 'end'})
//=> 'unico…'

cliTruncate('\u001B[31municorn\u001B[39m', 4);
//=> '\u001B[31muni\u001B[39m…'

// Truncate Unicode surrogate pairs
cliTruncate('uni\uD83C\uDE00corn', 5);
//=> 'uni\uD83C\uDE00…'

// Truncate fullwidth characters
cliTruncate('안녕하세요', 3);
//=> '안…'

// Truncate the paragraph to the terminal width
const paragraph = 'Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa.';
cliTruncate(paragraph, process.stdout.columns);
//=> 'Lorem ipsum dolor sit amet, consectetuer adipiscing…'

API

cliTruncate(text, columns, options?)

text

Type: string

The text to truncate.

columns

Type: number

The number of columns to occupy in the terminal.

options

Type: object

position

Type: string
Default: 'end'
Values: 'start' | 'middle' | 'end'

The position to truncate the string.

space

Type: boolean
Default: false

Add a space between the text and the ellipsis.

import cliTruncate from 'cli-truncate';

cliTruncate('unicorns', 5, {space: false});
//=> 'unic…'

cliTruncate('unicorns', 5, {space: true});
//=> 'uni …'

cliTruncate('unicorns', 6, {position: 'start', space: true});
//=> '… orns'

cliTruncate('unicorns', 7, {position: 'middle', space: true});
//=> 'uni … s'

preferTruncationOnSpace

Type: boolean
Default: false

Truncate the string from a whitespace if it is within 3 characters from the actual breaking point.

import cliTruncate from 'cli-truncate';

cliTruncate('unicorns rainbow dragons', 20, {position: 'start', preferTruncationOnSpace: true})
//=> '…rainbow dragons'

// without preferTruncationOnSpace
cliTruncate('unicorns rainbow dragons', 20, {position: 'start'})
//=> '…rns rainbow dragons'

cliTruncate('unicorns rainbow dragons', 20, {position: 'middle', preferTruncationOnSpace: true})
//=> 'unicorns…dragons'

cliTruncate('unicorns rainbow dragons', 6, {position: 'end', preferTruncationOnSpace: true})
//=> 'unico…'

// preferTruncationOnSpace would have no effect if space isn't found within next 3 indexes
cliTruncate('unicorns rainbow dragons', 6, {position: 'middle', preferTruncationOnSpace: true})
//=> 'uni…ns'

truncationCharacter

Type: string
Default: …

The character to use at the breaking point.

import cliTruncate from 'cli-truncate';

cliTruncate('unicorns', 5, {position: 'end'});
//=> 'unic…'

cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: '.'});
//=> 'unic.'

cliTruncate('unicorns', 5, {position: 'end', truncationCharacter: ''});
//=> 'unico'

Related

• wrap-ansi - Wordwrap a string with ANSI escape codes
• slice-ansi - Slice a string with ANSI escape codes